import { HooksDemos } from "@/lib/@docs/demos/src";
import { Layout } from "@/layout";
import { MDX_DATA } from "@/mdx";

export default Layout(MDX_DATA.useHotkeys);

## Usage

`use-hotkeys` accepts as its first argument an array of hotkeys and handler tuples:

- `hotkey` - hotkey string, for example `ctrl+E`, `shift+alt+L`, `mod+S`
- `handler` - event handler called when a given combination was pressed
- `options` - object with extra options for hotkey handler

```tsx
import { useHotkeys } from "@mantine/hooks";

function Demo() {
  // ctrl + J and ⌘ + J to toggle color scheme
  // ctrl + K and ⌘ + K to search
  useHotkeys([
    ["mod+J", () => console.log("Toggle color scheme")],
    ["ctrl+K", () => console.log("Trigger search")],
    ["alt+mod+shift+X", () => console.log("Rick roll")],
  ]);

  return null;
}
```

The second argument is a list of HTML tags on which hotkeys should be ignored.
By default, hotkeys events are ignored if the focus is in `input`, `textarea` and `select` elements.

```tsx
import { useHotkeys } from "@mantine/hooks";

function Demo() {
  // Ignore hotkeys events only when focus is in input and textarea elements
  useHotkeys(
    [["ctrl+K", () => console.log("Trigger search")]],
    ["INPUT", "TEXTAREA"]
  );

  // Empty array – do not ignore hotkeys events on any element
  useHotkeys([["ctrl+K", () => console.log("Trigger search")]], []);
}
```

## Targeting elements

`use-hotkeys` hook can work only with document element, you will need to create your own event listener
if you need to support other elements. For this purpose, `@mantine/hooks` package exports `getHotkeyHandler` function
which should be used with `onKeyDown`:

<Demo data={HooksDemos.useHotkeysDemo} />

With `getHotkeyHandler` you can also add events to any dom node using `.addEventListener`:

```tsx
import { getHotkeyHandler } from "@mantine/hooks";

document.body.addEventListener(
  "keydown",
  getHotkeyHandler([
    ["mod+Enter", () => console.log("Submit")],
    ["mod+S", () => console.log("Save")],
  ])
);
```

## Supported formats

- `mod+S` – detects `⌘+S` on macOS and `Ctrl+S` on Windows
- `ctrl+shift+X` – handles multiple modifiers
- `alt + shift + L` – you can use whitespace inside hotkey
- `ArrowLeft` – you can use special keys using [this format](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values)

## Types

`@mantine/hooks` exports `HotkeyItemOptions` and `HotkeyItem` types:

```tsx
interface HotkeyItemOptions {
  preventDefault?: boolean;
}

type HotkeyItem = [string, (event: KeyboardEvent) => void, HotkeyItemOptions?];
```

`HotkeyItem` type can be used to create hotkey items outside of `use-hotkeys` hook:

```tsx
import { HotkeyItem, useHotkeys } from "@mantine/hooks";

const hotkeys: HotkeyItem[] = [
  [
    "mod+J",
    () => console.log("Toggle color scheme"),
    { preventDefault: false },
  ],
  ["ctrl+K", () => console.log("Trigger search")],
  ["alt+mod+shift+X", () => console.log("Rick roll")],
];

useHotkeys(hotkeys);
```

## Definition

```tsx
function useHotkeys(
  hotkeys: HotkeyItem[],
  tagsToIgnore?: string[],
  triggerOnContentEditable?: boolean
): void;
```
